<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>OCCI Walkthrough</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.75.2"/></head><body><div class="article" title="OCCI Walkthrough"><div class="titlepage"><div><div><h2 class="title"><a id="id36063441"/>OCCI Walkthrough</h2></div></div><hr/></div><div class="section" title="Overview"><div class="titlepage"><div><div><h2 class="title"><a id="id36063450"/>Overview</h2></div><div><h3 class="subtitle">THIS WALKTHROUGH DOCUMENT DOES NOT REFLECT THE CURRENT STATE OF
    THE SPECIFICATION. IT WILL BE UPDATED ON PUBLICATION.</h3></div></div></div><p>The Open Cloud Computing Interface (OCCI) is an API for managing
    cloud infrastructure services (also known as Infrastructure as a Service
    or IaaS), which strictly adheres to REpresentational State Transfer (REST)
    principles and is closely tied to HyperText Tranfer Protocol (HTTP). For
    simplicity and scalability reasons it specifically avoids Remote Procedure
    Call (RPC) style interfaces and can essentially be implemented as a
    horizontally scalable document repository with which both nodes and
    clients interact.</p><p>This document describes a step-by-step walkthrough of performing
    various tasks as at the time of writing.</p></div><div class="section" title="Getting Started"><div class="titlepage"><div><div><h2 class="title"><a id="id36063472"/>Getting Started</h2></div></div></div><h3><a id="id36063478"/>Connecting</h3><p>Each implementation has a single OCCI end-point URL (we'll use
    http://example.com/) and everything needed to know is linked from this
    point - configuring clients is just a case of providing this parameter. In
    the simplest case, the end-point may contain only a single resource, for
    example, a hypervisor burnt into the BIOS of a motherboard that exposes
    compute resources, a network switch/router exposing network resources or a
    SAN exposing storage resources. At the other end of the spectrum the
    end-point may provide access to a global cloud infrastructure (e.g. the
    "Great Global Grid" or GGG). You will only ever see those resources to
    which you have access to (typically all of them for a private cloud or a
    small subset for a public cloud) and flexible categorisation. The search
    extension provides fine-grained control which resources are returned,
    allowing OCCI to handle the largest of installations. The end-point is
    always connected over HTTP(S) and given the simplicity of the interface
    most user-agents are suitable, including libraries (e.g. urllib2, LWP),
    command line tools (e.g. curl, wget) and full blown browsers (e.g.
    Firefox).</p><h3><a id="id36063484"/>Authenticating</h3><p>When you connect you will normally be challenged to authenticate via
    HTTP (this is not always the case - in secure/offline environments it may
    not be necessary) and will need to do so via the specified mechanism. It
    is anticipated that most implementations will require HTTP Basic
    Authentication over SSL/TLS so at the very least you should support this,
    but more advanced mechanisms such as NTLM or Kerberos may be deployed.
    Certain types of accesses such as a compute resource querying OCCI for
    introspection and configuration may be possible anonymously but only
    having already been authenticated by interface and/or IP address. Should
    you be redirected by the API to a node, storage device, etc. (for example,
    to retrieve a large binary representation) then the OCCI provider should
    provide means to transparently authenticate the currently authenticated
    user. That is, a single set of credentials and a single sign-on is all
    that is required to access the entire system from any point.</p><h3><a id="id36063490"/>Representations</h3><p>As the resource itself (e.g. a physical machine, storage array or
    network switch) cannot be transferred over HTTP we instead make available
    one or more representations of that resource. For example, an API modeling
    a person might return a picture, fingerprints, identity document(s) or
    even a digitised DNA sequence, but not the person themselves. A circle
    might be represented by SVG drawing primatives or any three distinct
    points on the curve. For cloud infrastructure there are many useful
    representations, and while OCCI recommends a number of them for
    interoperability purposes, an implementation is free to implement others
    in order to best serve the specific needs of their users and to
    differentiate from other offerings. Other examples include:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>Open Cloud Computing Interface (OCCI) descriptor format
        (application/occi+xml)</p></li><li class="listitem"><p>Open Virtualisation Format (OVF) file
        (application/ovf+xml?)</p></li><li class="listitem"><p>Open Virtualisation Archive (OVA) file
        (application/x-ova?)</p></li></ul></div><p>Other, albeit lesser representations, could include:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>Screenshot of the console (image/png)</p></li><li class="listitem"><p>Access to the console (application/x-vnc)</p></li></ul></div><p>The client indicates which representation(s) it desires by way of
    HTTP Content Negotiation using the HTTP Accept header and if the server is
    unable to satisfy the request then it should return HTTP 406 Not
    Acceptable. The client can also request the rendering via URL extension,
    if the server supports this option.</p><h3><a id="id36063555"/>Descriptors</h3><p>OCCI defines a simple attribute-based (key/value) descriptor format
    for cloud infrastructure resources. These infrastructure resources as
    defined by OCCI are:</p><div class="glosslist"><dl><dt><span class="bold"><strong>Compute:</strong></span></dt><dd><p>Provides computational services, ranging from dedicated
          physical machines (e.g. Dedibox) to virtual machines (e.g. Amazon
          EC2) to slices/zones/containers (e.g. Mosso Cloud Servers).</p></dd><dt><span class="bold"><strong>Network:</strong></span></dt><dd><p>Provides connectivity between machines and the outside world.
          Usually virtual and may or may not be connected to a physical
          segment.</p></dd><dt><span class="bold"><strong>Storage:</strong></span></dt><dd><p>Provides storage services, typically via magnetic mass storage
          devices (e.g. hard drives, RAID arrays, SANs).</p></dd></dl></div><p>Given the simplicity of the format it is trivial to translate
    between wire formats including plain text, JSON, XML and others
    <em><span class="remark">&lt;--| Insert alternative examples |--&gt;</span></em> . For
    example:</p><pre class="screen">occi.compute.cores 2
compute.speed 3200
compute.memory 2048</pre><h3><a id="id36063629"/>Identifiers</h3><p>Each resource is identified by its dereferenceable URL which is by
    definition unique, giving information about the origin and type of the
    resource as well as a local identifier. The combination of both forms a
    globally unique compound key.<em><span class="remark"> &lt;--| Is this necessary
    here?</span></em> The primary drawback is that the more information that goes
    into the key (and therefore the more transparent it is), the more likely
    it is to change. For example, if you migrate a resource from one
    implementation to another then its identifier will change (though in this
    instance the source should provide a HTTP 301 Moved Permanently response
    along with the new location, assuming it is known, or HTTP 410 Gone
    otherwise).<em><span class="remark">|--&gt;</span></em></p><p>In order to realise the benefit of transparent, dereferenceable
    identifiers while still being able to track resources through their entire
    lifecycle an immutable UUID attribute should be allocated which will
    remain with the resource throughout its life. This is particularly
    important where the same resource (e.g. a network) appears in multiple
    places.</p><p>New implementations should use type-4 random UUIDs, as these can be
    safely allocated by any OCCI-compliant provider without consulting a
    register/sequence. Where existing identifiers are available they should be
    used instead (e.g.
    http://an.occi.provider.com/compute/ami-ef48af86).</p></div><div class="section" title="Operations"><div class="titlepage"><div><div><h2 class="title"><a id="id36063665"/>Operations</h2></div></div></div><h3><a id="id36063671"/>Create</h3><p>To create a resource simply POST the resource representation to the
    appropriate collection (e.g. /compute, /network or /storage) using the
    application/x- www-form-urlencoded format (used by HTML forms) or in
    another supported format (e.g. OVF):</p><pre class="screen">POST /compute HTTP/1.1
Host: example.com
Content-Length: 35
Content-Type: application/x-www-form-urlencoded

compute.cores=2&amp;compute.memory=2048</pre><p>Rather than generating the new resource from scratch you may also be
    given the option <em><span class="remark">&lt;--| Templates are not explained in the
    walkthrough </span></em>to GET a template <em><span class="remark">|--&gt; </span></em>and
    <em><span class="remark">&lt;--| Semantic differences between the 2| </span></em>POST or PUT
    <em><span class="remark">|--&gt; </span></em>it back, for example, where "small", "medium" and
    "large" templates or pre-configured appliances are offered.</p><h3><a id="id36063705"/>Retrieve</h3><p>The simplest command is to retrieve a single resource by conducting
    a HTTP GET on its URL (which doubles as its identifier):</p><pre class="screen">GET /compute/b10fa926-41a6-4125-ae94-bfad2670ca87 HTTP/1.1
Host: example.com</pre><p>This will return <em><span class="remark">a HTTP 300 Multiple Choices response
    containing a list of available representations for the resource as well as
    a suggestion in the form of a HTTP Location: header of</span></em> the
    default rendering, which should be HTML (thereby allowing standard
    browsers to access the API directly). An arbitrary number of alternatives
    may also be returned by way of HTTP Link: headers. <em><span class="remark">&lt;--| this
    requires 2 calls by default |--&gt;</span></em></p><p>If you just need to know what representations are available you
    should make a HEAD request instead of a GET - this will return the
    metadata in the headers without the default rendering.</p><p>Some requests, such as the collections returned using the search
    extension, will need to return a collection of resources. There are two
    concepts that are supported:</p><div class="glosslist"><dl><dt>Pass-by-reference:</dt><dd><p>A plain text or HTML list of links is provided but each needs
          to be retrieved separately, resulting in O(n+1) performance.</p></dd><dt>Pass-by-value:</dt><dd><p>A wrapper format such as Atom is used to deliver [links to]
          the content as well as the metadata (e.g. links, associations,
          caching information, etc.), resulting in O(1) performance.</p></dd></dl></div><h3><a id="id36063770"/>Update</h3><p>Updating resources is trivial - simply GET the resource, modify it
    as necessary and PUT <em><span class="remark">&lt;--| What about someone using POST?
    --&gt;</span></em> it back where you found it.</p><h3><a id="id36063782"/>Delete</h3><p>Simply <code class="computeroutput">DELETE</code> the resource:</p><pre class="screen">DELETE /compute/b10fa926-41a6-4125-ae94-bfad2670ca87 HTTP/1.1
Host: example.com</pre></div><div class="section" title="Resource Child Collections"><div class="titlepage"><div><div><h2 class="title"><a id="id36063796"/>Resource Child Collections</h2></div></div></div><p>Each resource may expose collections for functions such as logging,
    auditing, change control, documentation and other operations (e.g.
    http://example.com/compute/123/log/456) in addition to any required by
    OCCI. As usual CRUD operations map to HTTP verbs (as above) and clients
    can either PUT entries directly if they know or will generate the
    identifiers, or POST them to the collection if this will be handled on the
    server side (using POST Once Exactly (POE) to ensure idempotency).</p><h3><a id="id36063810"/>Requests</h3><p><em><span class="remark">&lt;--| This section must reference somewhere that lists
    these </span></em>Requests <em><span class="remark">|--&gt;</span></em>are used to trigger state
    changes and other operations such as backups, snapshots, migrations and
    invasive reconfigurations (such as storage resource resizing). Those that
    do not complete immediately (returning HTTP 200 OK or similar) must be
    handled asynchronously (returning HTTP 201 Accepted or similar).</p><pre class="screen">POST /compute/123/requests HTTP/1.1
Host: example.com
Content-Length: 35
Content-Type: application/x-www-form-urlencoded

state=shutdown&amp;type=acpioff</pre><p>The actual operation may not start immediately (for example, backups
    which are only handled daily at midnight) and may take some time to
    complete (for example a secure erase which requires multiple passes over
    the disk). Clients can poll for status periodically or use server push (or
    a non-HTTP technology such as XMPP) to monitor for events.</p></div></div></body></html>
